<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>feed4j quickstart</title>
</head>
<body>
<h1>Quickstart</h1>
<p>In order to use the feed4j parser in your Java software, you have to make visible the <em>feed4j.jar</em> file to your application adding it to the CLASSPATH. Since the feed4j library depends on third parties jars (placed in the <em>lib</em> directory of the distribution package) you also have to add them to the CLASSPATH. </p>
<h2>Requirements</h2>
<p>feed4j requires a Java runtime environment J2SE 1.4 or later.</p>
<h2>The feed parser</h2>
<p>The use of the feed parser (class <em>it.sauronsoftware.feed4j.FeedParser</em>) is a one-step operation: </p>
<pre>Feed feedRepresentation = FeedParser.parse(feedUrl);</pre>
<p>Once you have retrieved a feed representation object (class <em>it.sauronsoftware.feed4j.bean.Feed</em>) you can ask it everything about the parsed XML feed. The feed representation is splitted in two parts: a feed header and a feed items collection. The header contains information about the whole feed, such its source URL, its title, its description and so on. Every feed item represents a news story, and it is mainly composed by a title and a URL, but it can also contains HTML and plain text descriptions, publication and modification dates, several enclosures etc.</p>
<p>The feed object representation provided by feed4j can be mastered in minutes: just take a look to the javadocs that come with the distribution package.</p>
<p>A quick and complete example:</p>
<pre>package it.sauronsoftware.feed4j.example1;

import java.net.URL;

import it.sauronsoftware.feed4j.FeedParser;
import it.sauronsoftware.feed4j.bean.Feed;
import it.sauronsoftware.feed4j.bean.FeedHeader;
import it.sauronsoftware.feed4j.bean.FeedItem;

public class FeedExample {

	public static void main(String[] args) throws Exception {
		
		URL url = new URL(&quot;http://www.scarletgothica.com/rss_en.php&quot;);
		
		Feed feed = FeedParser.parse(url);
		
		System.out.println(&quot;** HEADER **&quot;);
		FeedHeader header = new FeedHeader();
		System.out.println(&quot;Title: &quot; + header.getTitle());
		System.out.println(&quot;Link: &quot; + header.getLink());
		System.out.println(&quot;Description: &quot; + header.getDescription());
		System.out.println(&quot;Language: &quot; + header.getLanguage());
		System.out.println(&quot;PubDate: &quot; + header.getPubDate());
		
		System.out.println(&quot;** ITEMS **&quot;);
		int items = feed.getItemCount();
		for (int i = 0; i &lt; items; i++) {
			FeedItem item = feed.getItem(i);
			System.out.println(&quot;Title: &quot; + item.getTitle());
			System.out.println(&quot;Link: &quot; + item.getLink());
			System.out.println(&quot;Plain text description: &quot; + item.getDescriptionAsText());
			System.out.println(&quot;HTML description: &quot; + item.getDescriptionAsHTML());
			System.out.println(&quot;PubDate: &quot; + item.getPubDate());
		}
		
	}

}</pre>
<p>A more complex example is in the <em>examples/example2</em> directory inside the distribution package.</p>
<h2>Catching the exceptions </h2>
<p>The <em>FeedParser.parse()</em> method can throw several exceptions, depending on the kind of the encountered problem:</p>
<ul>
  <li><em>FeedIOException</em>: the feed cannot be retrieved due to an I/O problem.</li>
  <li><em>FeedXMLParseException</em>: the file has been retrieved, but it doesn't look to be valid XML.</li>
  <li><em>UnsupportedFeedException</em>: the feed has been retrieved and parsed as a XML document, but its contents doesn't match one of the feed formats supported by feed4j.</li>
</ul>
<p>Since all those exceptions extend the <em>FeedException</em> class, you can handle them one by one or all together with a sole catch block:</p>
<pre>Feed feed;
try {
	feed = FeedParser.parse(feedUrl);
} catch (FeedIOException e) {
	// one
} catch (FeedXMLParseException e) {
	// by
} catch (UnsupportedFeedException e) {
	// one
}

try {
	feed = FeedParser.parse(feedUrl);
} catch (FeedException e) {
	// all together
}</pre>
<h2>Supported feed formats </h2>
<p>The feed4j parser can currently handle the following XML feed formats:</p>
<ul>
  <li>RSS 1.0 + Dublin Core tags</li>
  <li>RSS 2.0</li>
  <li>RSS 0.91 and 0.92, since a valid RSS 0.91 or 0.92 feed is also a valid RSS 2.0 feed</li>
  <li>Atom 0.3</li>
  <li>Atom 1.0 (IETF standard)</li>
</ul>
<h2>Handling custom tags</h2>
<p>XML feeds are flexible and can be extended with custom or third-parties tags. The feed4j parser helps you in handling them giving &quot;raw access&quot; to unhandled tags. In example: if the items in your XML feed are expected to contain a custom tag called &quot;phone-number&quot;, whose namespace is &quot;http://www.mysite.org/myCustomTags&quot;, you can gain access to its value as follows:</p>
<pre>String value = feedItem.getElementValue(
	"http://www.mysite.org/myCustomTags", "phone-number"
);</pre>
<p>In the package <em>it.sauronsoftware.feed4j.bean</em> you can find the class <em>RawElement</em>, which is a raw informations container. Since <em>FeedHeader</em>, <em>FeedItem</em>, <em>FeedImage</em> and <em>FeedEnclosure</em> extend <em>RawElement</em> you can ever access raw data. So you will handle standard informations with structured methods like <em>getTitle()</em>, <em>getLink()</em> and <em>getPubDate()</em>, while  non-standard informations will be accessed in a raw way, with methods like <em>getElement()</em>, <em>getAttribute()</em> and <em>getNode()</em>. Please refer to the feed4j javadocs for a  complete features list.</p>
</body>
</html>
